package org.jpropelleralt.node;

import org.jpropelleralt.path.PathStep;
import org.jpropelleralt.ref.Ref;

/**
 * A {@link Node} having a description {@link Ref}
 * with a {@link String} value.
 * The description should be a relatively brief
 * description of the {@link Node} itself.
 * Note that in general, a {@link Described} {@link Node}
 * will also implement {@link Named}. In this case, the
 * description should not duplicate the contents of 
 * {@link Named#name()}, and should be designed to
 * follow on from the name - typically, a display will
 * use the format:
 * <br/>
 * <br/>
 * Name, Description
 * <br/>
 * <br/>
 * or a two-line format
 * <br/>
 * <br/>
 * Name
 * <br/>
 * Description
 * <br/>
 * <br/>
 */
public interface Described extends Node {
	
	/**
	 * Get the description of this {@link Node}
	 * Note that the {@link Ref} returned from this
	 * method must have the ref-name "description" in
	 * this {@link Node}.
	 * @return	{@link Node}'s description, as a {@link Ref}
	 */
	public Ref<String> description();
	
	/**
	 * The ref-name used within {@link Described} nodes to
	 * refer to their description property.
	 */
	public final static String NAME = "description";
	
	/**
	 * {@link PathStep} from a {@link Described} to its
	 * {@link Described#description()} {@link Ref}.
	 */
	PathStep<Described, String> toDescription = new PathStep<Described, String>() {
		public Ref<String> transform(Described s) {
			return s.description();
		};
	};
}
